home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Sound / LAME / WarpOS / src / STYLEGUIDE < prev    next >
Encoding:
Text File  |  2000-11-01  |  6.8 KB  |  188 lines
  1. * The LAME API is frozen.  Poorly designed as it is, don't change it, 
  2.   and add to it sparingly.
  3.  
  4. * Don't take it upon yourself to go through LAME with the sole purpose
  5.   of updating everything to match this guide.  Especially important:
  6.   don't change the spacing, indentation, curly braces, etc, 
  7.   in routines you did not write.
  8.  
  9. * If you want to make a change which effects many many functions,
  10.   please check with the maintainer first.
  11.  
  12. * Respect the indentation of the author of the original function.
  13.   If the indentation is not consistent, use 4.
  14.  
  15. * Don't use tabulators (the character with the value '\t') in source code,
  16.   especially these with a width of unequal 8. Lame sources are using
  17.   different sizes for tabulators.
  18.  
  19. * Don't set the macro NDEBUG in alpha versons.
  20.   NDEBUG should be set for beta versions.
  21.  
  22. * check important assumptions with an assert()
  23.  
  24. * use int for all integer quantities.  
  25.   LAME requires 32 bit ints, so you can assume int is at least 32 bits.  
  26.   Don't use 'long'.  Don't use 'unsigned' unless ABSOLUTELY necessary.
  27.   Don't use 'char' just to save bytes.  If 64 bits is required, use int64.
  28.  
  29.   Annnotation:
  30.   ISO C calls the 64 bit int type not int64 but int64_t.
  31.  
  32. * Avoid using float or double, and instead use: (defined in machine.h).  
  33.  
  34.   FLOAT    for variables which require at least 32bits
  35.   FLOAT8   for variables which require at least 64bits
  36.  
  37.   On some machines, 64bit will be faster than 32bit.  Also, some math
  38.   routines require 64bit float, so setting FLOAT=float will result in a
  39.   lot of conversions.
  40.  
  41.   Annotation (pfk):
  42.   The new ISO C standard passed in autumn 1999 has defined new types for
  43.   exactly this reason. There are called float_least32_t and float_least64_t
  44.   and have at least the advantage that you not need to explain their
  45.   meaning. 
  46.  
  47.   Annotation (mt):  
  48.   we will adopt this convention in Jan 1, 2003.
  49.  
  50.  
  51. * The internal representation of PCM samples in type 'sample_t',
  52.   currently this is a FLOAT.
  53.  
  54. * Use SI base units. Lame mixes Hz, kHz, kbps, bps. This is mess.
  55.  
  56.   Example:
  57.         float     wavelength_green = 555.e-9;
  58.         unsigned  data_rate        = 128000;
  59.         float     lowpass_freq     = 12500.;
  60.   
  61.   Converting between user input and internal representation should be done
  62.   near the user interface, not in the most inner loop of an utility
  63.   function.
  64.  
  65. ----------------------------------------------------------------------------------
  66. Edited version of the Linux Kernel Style Guide:
  67. ----------------------------------------------------------------------------------
  68.  
  69.                 Chapter 1: Indentation
  70.  
  71. Respect the indentation of the author of the original function.
  72. If the indentation is not consistent, don't change it.  If
  73. you are so anal-retentive about these things and you can't
  74. bare to even look at code with poor indentation, change it to 4.
  75.  
  76.  
  77.                 Chapter 2: Placing Braces
  78.  
  79. The other issue that always comes up in C styling is the placement of
  80. braces.  Unlike the indent size, there are few technical reasons to
  81. choose one placement strategy over the other, but the preferred way, as
  82. shown to us by the prophets Kernighan and Ritchie, is to put the opening
  83. brace last on the line, and put the closing brace first, thusly:
  84.  
  85.         if (x is true) {
  86.                 we do y
  87.         }
  88.  
  89. However, there is one special case, namely functions: they have the
  90. opening brace at the beginning of the next line, thus:
  91.  
  92.         int function(int x)
  93.         {
  94.                 body of function
  95.         }
  96.  
  97. Heretic people all over the world have claimed that this inconsistency
  98. is ...  well ...  inconsistent, but all right-thinking people know that
  99. (a) K&R are _right_ and (b) K&R are right.  Besides, functions are
  100. special anyway (you can't nest them in C). 
  101.  
  102. Note that the closing brace is empty on a line of its own, _except_ in
  103. the cases where it is followed by a continuation of the same statement,
  104. ie a "while" in a do-statement or an "else" in an if-statement, like
  105. this:
  106.  
  107.         do {
  108.                 body of do-loop
  109.         } while (condition);
  110.  
  111. and
  112.  
  113.         if (x == y) {
  114.                 ..
  115.         } else if (x > y) {
  116.                 ...
  117.         } else {
  118.                 ....
  119.         }
  120.                         
  121. Rationale: K&R. 
  122.  
  123. Also, note that this brace-placement also minimizes the number of empty
  124. (or almost empty) lines, without any loss of readability.  Thus, as the
  125. supply of new-lines on your screen is not a renewable resource (think
  126. 25-line terminal screens here), you have more empty lines to put
  127. comments on. 
  128.  
  129.  
  130.                 Chapter 3: Naming
  131.  
  132. C is a Spartan language, and so should your naming be.  Unlike Modula-2
  133. and Pascal programmers, C programmers do not use cute names like
  134. ThisVariableIsATemporaryCounter.  A C programmer would call that
  135. variable "tmp", which is much easier to write, and not the least more
  136. difficult to understand. 
  137.  
  138. HOWEVER, while mixed-case names are frowned upon, descriptive names for
  139. global variables are a must.  To call a global function "foo" is a
  140. shooting offense. 
  141.  
  142. GLOBAL variables (to be used only if you _really_ need them) need to
  143. have descriptive names, as do global functions.  If you have a function
  144. that counts the number of active users, you should call that
  145. "count_active_users()" or similar, you should _not_ call it "cntusr()". 
  146.  
  147. Encoding the type of a function into the name (so-called Hungarian
  148. notation) is brain damaged - the compiler knows the types anyway and can
  149. check those, and it only confuses the programmer.  No wonder MicroSoft
  150. makes buggy programs. 
  151.  
  152. LOCAL variable names should be short, and to the point.  If you have
  153. some random integer loop counter, it should probably be called "i". 
  154. Calling it "loop_counter" is non-productive, if there is no chance of it
  155. being mis-understood.  Similarly, "tmp" can be just about any type of
  156. variable that is used to hold a temporary value. 
  157.  
  158.  
  159.                 
  160.                 Chapter 4: Functions
  161.  
  162. Document functions.  
  163.  
  164. Keep functions as modular as possible.  But don't adhere to artificial
  165. line number limitations.  For example, lame_encode_frame() encodes a
  166. single MP3 frame and is a long sequence of function calls.  It makes
  167. no sense to break this into two or more routines.
  168.  
  169.  
  170.  
  171.                 Chapter 5: Commenting
  172.  
  173. Comments are good, but there is also a danger of over-commenting.  NEVER
  174. try to explain HOW your code works in a comment: it's much better to
  175. write the code so that the _working_ is obvious, and it's a waste of
  176. time to explain badly written code. 
  177.  
  178. Generally, you want your comments to tell WHAT your code does, not HOW. 
  179. Also, try to avoid putting comments inside a function body: if the
  180. function is so complex that you need to separately comment parts of it,
  181. you should probably go back to chapter 4 for a while.  You can make
  182. small comments to note or warn about something particularly clever (or
  183. ugly), but try to avoid excess.  Instead, put the comments at the head
  184. of the function, telling people what it does, and possibly WHY it does
  185. it. 
  186.  
  187.  
  188.